home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / DCLIB1.ZIP / README.TXT < prev   
Encoding:
Text File  |  1995-06-06  |  8.9 KB  |  226 lines
  1. //////////////////////////////////////////////////////////////////////////
  2.         THIS FILE CONTAINS IMPORTANT INFORMATION AND INSTRUCTIONS
  3. //////////////////////////////////////////////////////////////////////////
  4.  
  5. /*************************************************************************/
  6. /*  The author makes no warranty of any kind, expressed or implied,      */
  7. /*  with regard to the Data Compression Library, and to the accuracy     */
  8. /*  of the specifications.                                               */
  9. /*  The author shall not be liable for any loss or damages resulting     */
  10. /*  from the use of any of the programs supplied.                        */
  11. /*                                                                       */
  12. /*************************************************************************/
  13.  
  14. ///////////////////////////////////////////////////////////////////////////
  15.  For a FASTER DECOMPRESSION library (approx. 15-20%) send £19.99 or $44.99
  16.                            to the address below
  17. ///////////////////////////////////////////////////////////////////////////
  18.  
  19. The data compression libraries are specifically designed for the real time
  20. decompression of graphical sprite type data. They may or may not be
  21. suitable for other purposes.
  22.  
  23.  
  24. ----------------------------------------------------------------------------
  25.                     Data Compression Library Files
  26.  
  27. The Shareware version of the Data Compression Libraries contains the 
  28. following files. Feel free to distribute the Data Compression Libraries.
  29.  
  30. The following files are included in the DCLLIB archive :
  31.  
  32. DCL_386R.LIB      - Watcom C 386 Register based library
  33. DCL_386S.LIB      - Watcom C 386 Stack based library
  34. DCL_386.H         - Header file for Data Compression Library
  35. EXAMPLE.C         - An example program for DCLLIB
  36. EXAMPLE.EXE       - The example program, already compiled and linked
  37. README.TXT        - This File
  38. REGISTER.TXT      - If you want the faster libraries, or want to 
  39.                     register so you can distribute your code then
  40.                     you need to read this.
  41.  
  42.  
  43. ----------------------------------------------------------------------------
  44.  
  45. ----------------------------------------------------------------------------
  46.                         Using The Libraries
  47.  
  48. These Libraries are compiled specifically for WATCOM 386 C. There are no
  49. other ports at this moment in time.
  50. Use the library like any other, simply include the header in your program
  51.  
  52. #include "dcl_386.h"
  53.  
  54. And link one of the .LIB files into your code. There are two versions of the
  55. library, one for register based parameter passing, and one for stack based
  56. parameter passing.
  57.  
  58.  
  59.  
  60. /************************************************************************/
  61.                  THE DATA COMPRESSION LIBRARY FUNCTIONS
  62. /************************************************************************/
  63.  
  64. There are four functions which you will need to use, these are listed as ...
  65.  
  66. 1. DCL_init_compress     - Initialises memory for library
  67. 2. DCL_close_compress    - Deinitialises memory for library
  68. 3. DCL_shrink            - Compress data
  69. 4. DCL_expand            - Expand data
  70.  
  71. Here is a more detailed look at the functions and how they work.
  72.  
  73. ------------------------------------------------------------------------
  74. FUNCTION : Initialise Compression Library
  75. int DCL_init_compress(unsigned int uncomp_buf, unsigned int comp_buf);
  76.  
  77. RETURNS:
  78. 0    - if unsuccessfull (not enough memory).
  79. 1    - if successfull
  80.  
  81. EXAMPLE:
  82. error=DCL_init_compress(20000,20000);
  83.  
  84. if(error==NULL) {
  85.     printf(Cannot alocate memory !\n");
  86.     exit(1);
  87. }
  88.  
  89. This example simply allocates 20k for both compression and decompression.
  90. ie. the size of the compressed and uncompressed sprite frame must not
  91. exceed 20,000 bytes. 
  92.  
  93. NOTES:
  94. All this function does is allocates two blocks of memory, one is the
  95. uncompressed buffer (uncomp_buf), and the other is the compressed buffer
  96. (comp_buf). The arguments both represent number of bytes to allocate.
  97.  
  98. The decompression uses the memory in uncomp_buf to decompress to (see
  99. the relevant function, it will return a pointer to this location), and
  100. the compression routine will compress to the comp_buf.
  101.  
  102. These two buffers are simply located in global memory and are used to
  103. reduce the chance of memory fragmentation. You could set these arguments
  104. just before compressing, and decompressing, if you knew the exact sizes
  105. of both. However, if you don't know exactly how big these need to be
  106. then just make them as big as you will need.
  107.  
  108. For example, if all your sprites to be compressed are under 15k per frame
  109. then make both buffers 15k big. It might be a good plan to add on a bit for
  110. safety.
  111.  
  112. You only need to call this function once at the start of your program.
  113.  
  114. You can bypass this function manually. There is little reason why you would
  115. want to but, just incase, this is how to do it.
  116. There are two variables which are pointers to unsigned char. These are
  117.  
  118. unsigned char *DCL_tbuffer;
  119. unsigned char *DCL_dest;
  120.  
  121. These are globals, if you wish to use them just define them as external.
  122. The first is a pointer to the uncomp_buf, the second is a pointer to the
  123. comp_buf. You may allocate and reference these directly if you so wish.
  124.  
  125. ------------------------------------------------------------------------
  126. FUNCTION : Uninitialise compression library
  127. void DCL_close_compress(void);
  128.  
  129. RETURNS:
  130. nothing.
  131.  
  132. EXAMPLE:
  133. DCL_close_compress();
  134.  
  135. NOTES:
  136. This function should be called when you are finished either compressing
  137. or decompressing. All it does is free DCL_tbuffer and DCL_dest. Once again
  138. you could do this manually if you wish.
  139.  
  140. ------------------------------------------------------------------------
  141. FUNCTION : Compress some memory data
  142. unsigned char *DCL_shrink(unsigned char *source,unsigned int *length);
  143.  
  144. ARGUMENTS:
  145. source - A pointer to the start of the data you wish to compress.
  146. length - The number of bytes you wish to compress.
  147.  
  148. RETURNS:
  149. Pointer to compressed data (ie. globally allocated DCL_dest).
  150. Also returns the size of the uncompressed data in 'length'
  151.  
  152. EXAMPLE:
  153. compressed_data=DCL_shrink(source,&length);
  154.  
  155. NOTES:
  156. This function takes the data from the pointer 'source' and places it into
  157. the globally allocated destination (created when you did DCL_init_compress).
  158. It always returns a pointer to DCL_dest because that is where data is always
  159. compressed to.
  160.  
  161. ------------------------------------------------------------------------
  162. FUNCTION : Uncompress some memory data
  163. unsigned char *DCL_expand(unsigned char *source,unsigned int *length);
  164.  
  165. ARGUMENTS:
  166. source - A pointer to the start of the data you wish to uncompress.
  167. length - used for return only (see below).
  168.  
  169. RETURNS:
  170. Pointer to the uncompressed data (ie. globally allocated DCL_tbuffer).
  171. Also returns the size of the uncompressed data in 'length'
  172.  
  173. EXAMPLE:
  174. compressed_data=DCL_expand(source,&length);
  175.  
  176. NOTES:
  177. This function takes the data from the pointer 'source' and places it into
  178. the globally allocated destination (created when you did DCL_init_compress).
  179. It always returns a pointer to DCL_tbuffer because that is where data is 
  180. always uncompressed to.
  181.  
  182. -----------------------------------------------------------------------
  183.  
  184. GENERAL COMMENTS:
  185.  
  186. If things are still unclear then you should have a look at the example file
  187. 'example.c'.
  188.  
  189. There isn't much error checking here (apart from the memory allocation).
  190. It really is up to you to know what you are doing. This library is
  191. pretty simple, so not much is needed anyway.
  192.  
  193. The most likely way for the program to crash is if you dont allocate enough
  194. memory in DCL_init_compress. Because this library was designed specifically
  195. for sprites, it just allocates this Global memory once, then re-uses it for
  196. all compression and decompression. Remember that as they are single instances
  197. of global buffers, you will need to move or use the data BEFORE you try to
  198. 'expand' or 'shrink' again.
  199.  
  200. In the case of a sprite system, you would make this function 'invisible' by
  201. placing it inside your draw sprite routine, so just before drawing the sprite
  202. to screen or a buffer, you decompress it.
  203.  
  204. If the libraries seem a bit limited then sorry. They were written for for a
  205. specific use and it is possible that there are uses for which they are not
  206. particularly well suited. Once again, sorry, but I don't have time to write
  207. everything.
  208.  
  209. I will try to release more stuff in the future, but that really depends on
  210. how much support I get from you people. If you register and get the faster
  211. libraries then that will also be an incentive to myself. I'm thinking of
  212. an animation player next (lossy), because, apart from very expensive 
  213. commercial systems, there doesn't seem to be much about. Well, 
  214. thats another day ...
  215.  
  216.  
  217. Correspondence to :
  218.  
  219.             Dani Arrusi
  220.             6 Swan Road
  221.             West Drayton
  222.             Middlesex UB7 7JY
  223.             England
  224.  
  225. E-mail : dani@minor.demon.co.uk
  226.